home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / UTIL / DESKTOP / MEGABOARD / MegaBoard2 / Docs / ProgGuide < prev    next >
Text File  |  1996-01-28  |  19KB  |  641 lines
  1.                 Guide for writing Special icons for Megaboard 2
  2.                 -----------------------------------------------
  3. ----------------
  4. - Introduction -
  5. ----------------
  6. This file explains how to create new special icons for Megaboard, it will
  7. only be of interest to programmers, other users should refer to the "Guide"
  8. file for information on general use.
  9. For a step-by-step tutorial on creating a special icon see the ProgTutrl
  10. file.
  11.  
  12. ---------------------------------
  13. - Changes from earlier versions -
  14. ---------------------------------
  15. From version 2.00 onwards the method used by special icons has changed, this
  16. was necessary, since it relied on the code being called from BASIC, wheras
  17. MegaBoard 2 is written in C. See below for details.
  18.  
  19. ------------------
  20. - Relevant files -
  21. ------------------
  22. The files within Megaboard's application directory used by special icons are
  23. the script file named "Cstm_Scrpt" and the files contained in the "Special"
  24. subdirectory.
  25.  
  26. ----------------------
  27. - Creating new icons -
  28. ----------------------
  29. Creating a new icon consists of two steps, writing the icon's definition in
  30. the script file and writing a set of ARM code entry points needed to maintain
  31. the icon.
  32.  
  33. Icon definition commands
  34. ------------------------
  35. The script file consists of the following commands (Not case sensitive):
  36. *  Start_Icon
  37. *  Name:
  38. *  Author:
  39. *  Width:
  40. *  Height:
  41. *  Worksize:
  42. *  Update:
  43. *  Mouse_State:
  44. *  KeyPress_State:
  45. *  Message_State:
  46.    Start_Parameters
  47.    <Parameter name>:<default value>
  48.                  ...
  49.    <Parameter name>:<default value>
  50.    End_Parameters
  51. *  End_Icon
  52. The Commands marked with an asterisk are mandatory and must be present in
  53. every icon definition.
  54.  
  55. Writing an icon definition
  56. --------------------------
  57. An Icon definition always begins with the command Start_Icon, which may be
  58. preceded by any number of spaces, but otherwise must be the only item on the
  59. line.
  60. Start_Icon is followed on subsequent lines by a list of commands terminated
  61. by the End_Icon command.
  62.  
  63. Syntax of script commands
  64. -------------------------
  65. All commands except Start_Icon, End_Icon, Start_Parameters and
  66. End_Parameters have the following syntax:
  67. |<Spaces>|<Command>:|<Spaces>|<Value>
  68. Where items contained in || are optional.
  69. Example use:
  70.  
  71.      Width: 100
  72. ^^^^^      ^
  73.   ⇧        ⇧
  74. Leading   Spaces
  75. Spaces   separating
  76.  are      command
  77. ignored     and
  78.            value
  79.             are
  80.            also
  81.           ignored
  82. The command above sets the special icon's width to 100 OS units.
  83. The following commands, however, have the same effect:
  84. Width:100
  85. Width:                                                100
  86.                                              Width:100
  87.  
  88.  
  89. Command descriptions
  90. --------------------
  91. Now for a detailed description of script commands:
  92.  
  93. Name:
  94. -----
  95. The Name command sets the name of the icon as contained in the 'Special icon'
  96. submenu and in the Function names (described later), it must therefore comply
  97. with Basic V variable name restrictions.
  98. Note: Although the command is not case sensitive in this case the value is.
  99. Example:
  100. Name: Pointer
  101.  
  102. Author:
  103. -------
  104. You!
  105. This Command sets the name of the icon's author to be displayed in the Info
  106. Box for the icon.
  107. Example:
  108. Author: Fred Bloggs
  109.  
  110. Version:
  111. --------
  112. Sets the version number of the icon as displayed in the 'Info' box including
  113. the date, if required.
  114. Example:
  115. Version: 1.00 (19 Aug 1994)
  116.  
  117. Width:
  118. ------
  119. Sets the width of the icon in OS units. The value must be a decimal integer
  120. and a multiple of four.
  121. Example:
  122. Width: 100
  123.  
  124. Height:
  125. -------
  126. Sets the height of the icon in OS units. The value must be a decimal integer
  127. and a multiple of four.
  128. Example:
  129. Height: 100
  130.  
  131. Worksize:
  132. ---------
  133. Sets the amount of workspace the icon requires in bytes. The value must be a
  134. decimal integer.
  135. Example:
  136. Worksize: 100
  137.  
  138. Update:
  139. -------
  140. Defines how often the icon requires updating, the value must be one of the
  141. following words:
  142.  
  143. Continuous
  144. Second
  145. Minute
  146. Hour
  147. Day
  148. Never
  149.  
  150. A value of Continuous means the icon needs updating as often as possible.
  151. Pointer is an example of such an icon.
  152. A value of Second, Minute, Hour or Day mean the icon needs updating every
  153. Second, Minute, Hour or Day (what else!).
  154. Never means the icon's contents do not change with time and therefore it does
  155. not require updating. It is, however, updated whenever it receives a message,
  156. keypress or mouseclick.
  157.  
  158. Message_State:
  159. --------------
  160. Defines whether or not Wimp messages should be reported to the icon, the
  161. value must be either "On" or "Off".
  162.  
  163. Mouse_State:
  164. --------------
  165. Defines whether or not mouse clicks should be reported to the icon, the
  166. value must be either "On" or "Off".
  167.  
  168. Keypress_State:
  169. --------------
  170. Defines whether or not Keypresses should be reported to the icon, the
  171. value must be either "On" or "Off".
  172.  
  173. Menu_State:
  174. --------------
  175. Defines whether or not the icon has a menu associated with it, the value must
  176. be either "On" or "Off".
  177.  
  178. Start_Parameters
  179. ----------------
  180. Start_Parameters initiates the definition of parameters. It is followed by
  181. a list of parameter descriptions terminated by the Command "End_Parameters".
  182. Example:
  183. Start Parameters
  184.  
  185. A parameter description has the following format:
  186. |<Spaces>|<Name>:|<Spaces>|<default>
  187.  
  188. Where <name> is the name of the parameter (as displayed in the icons's
  189. submenu and <default> is its default value. As is initially displayed in
  190. the writeable parameter submenu item.
  191. Example:
  192. Pathname: adfs::4.$.Fred
  193.  
  194. Megaboard currently has a limit of 16 parameters per icon this will
  195. (hopefully) be altered in a later version.
  196.  
  197. End_Parameters
  198. --------------
  199. End_Parameters terminates a list of parameters.
  200.  
  201. Example of a parameter list:
  202. Start_Parameters
  203.   Pathname: adfs::4.$.Fred
  204.   Size: 1024
  205. End_Parameters
  206.  
  207. End_Icon
  208. --------
  209. End_icon terminates an icon definition
  210. Example:
  211. End_Icon
  212.  
  213. -------------------------
  214. - ARM code entry points -
  215. -------------------------
  216. A Megaboard special icon requires a file containing several blocks of ARM
  217. code function correctly. The file must have the following format:
  218.  
  219. Size of the first code block (including this word) (1 word)
  220. First code block (n words (must be a whol number of words))
  221.  
  222. Size of the second code block (1 word)
  223. Second code block (n words (must be a whole number of words))
  224.  
  225. ...
  226.  
  227. Size of the last code block (1 word)
  228. Last code block (n words (must be a whol number of words))
  229.  
  230. The following code blocks are required:
  231.   initialise
  232.   null
  233.   redraw
  234.   finish
  235.   save
  236.   load
  237.   message
  238.   mouse
  239.   key
  240.   menu
  241.   menu_select
  242.   menu_warning
  243. All of these blocks must be present in every entry points file regardless of
  244. whether a particular icon responds to all messages.
  245. Entry points are called using C function pointers, i.e. R13 points to a
  246. stack and MOV PC,R14 returns.
  247. Entry point code must be position independent.
  248. The entry points file should be named "Code" and placed in the directory
  249. "!MegaBoard.Special.<icon name>". Where <icon name> is the name specified in
  250. the definition. Any other files the icon reqiures should also be stored in
  251. this directory.
  252.  
  253. Technical details of the entry points
  254. -------------------------------------
  255.  
  256.                            INITIALISE
  257.                            ----------
  258. On entry:
  259.  
  260.     R0 - The X screen coordinate of the centre of the icon.
  261.     R1 - The Y screen coordinate of the centre of the icon.
  262.     R2 - The width of the icon.
  263.     R3 - The height of the icon.
  264.     R4 - A pointer to the icon's workspace.
  265.     R5 - A pointer to a list of parameters
  266.          R5+0     - first parameter string
  267.          R5+256   - second parameter string
  268.                     ...
  269.          R5+n*256 - last parameter string
  270.  
  271. On exit:
  272.  
  273. Offsets from the start of the code block:
  274.  
  275. -16: A% - New X screen coordinate
  276. -12: B% - New Y screen coordinate
  277. -8:  C% - New icon width
  278. -4:  D% - New icon height
  279.  
  280.  
  281. Purpose:
  282.  
  283. Initialise is called when the icon is first placed on MegaBoard i.e. when the
  284. user clicks on it's menu item. It should do any setting up the icon requires
  285. in order for redraw to be called and store any parameters.
  286.  
  287. Note: the BASIC variables A%-D% are altered from assembler with the
  288.       following code (with A% as an example):
  289.  
  290.    ADR        R11,variable       ;R11 points to the variable name
  291.    STMFD      R13!,{R14}         ;presverve R14 on the stack
  292.    MOV        R10,R14            
  293.    ADR        R14,done           ;point R14 to the address BASIC's variable
  294.                                   locator should return to.
  295.    ADD        PC,R10,#&3C        ;call BASIC's variable locator
  296.  
  297.   .done                          ;R0 now points to the variable's value
  298.    LDR        R1,newvalue
  299.    STR        R1,[R0]
  300.  
  301.   .variable EQUS A%+CHR$(10):ALIGN
  302.   .newvalue EQUD new_value%
  303.  
  304.  
  305.  
  306.  
  307.                                NULL
  308.                                ----
  309. On entry:
  310.  
  311.     R0 - The X screen coordinate of the centre of the icon.
  312.     R1 - The Y screen coordinate of the centre of the icon.
  313.     R2 - The width of the icon.
  314.     R3 - The height of the icon.
  315.     R4 - A pointer to the icon's workspace.
  316.  
  317. On exit:
  318.  
  319. Offsets from the start of the code block:
  320.  
  321. -16: A% - New X screen coordinate
  322. -12: B% - New Y screen coordinate
  323. -8:  C% - New icon width
  324. -4:  D% - New icon height
  325.  
  326. Purpose:
  327.  
  328. Null is called if the icon's script file entry has not set its update state
  329. to "Never". Megaboard attempts to call it at the interval specified by the
  330. update state, this is, however not guaranteed.
  331.  
  332.  
  333.                                REDRAW
  334.                                ------
  335. On entry:
  336.  
  337.     R0 - The X screen coordinate of the centre of the icon.
  338.     R1 - The Y screen coordinate of the centre of the icon.
  339.     R2 - The width of the icon.
  340.     R3 - The height of the icon.
  341.     R4 - A pointer to the icon's workspace.
  342.  
  343. On exit:
  344.  
  345.      ---
  346.  
  347. Purpose:
  348.  
  349. Redraw is called whenever the icon on the screen requires updating, e.g. when
  350. all or part of it is uncovered by a moved window, and immediately after ALL
  351. other entry points except finish and those relating to menus. It should draw
  352. the icon at the screen coordinates in R0,R1.
  353.  
  354. Note: Some restrictions apply within this entry point:
  355.       - It is possible that screen output is redirected to a sprite when
  356.         redraw is called. If this is the case then OS_ReadModeVariable will
  357.         not return the correct values for the current mode, but for the
  358.         sprite.
  359.       - In order for the icon to be redrawn at the correct position redraw
  360.         is sometimes called with the graphics origin not at (0,0) most
  361.         RISC OS calls that output to the screen acknowledge this and modify
  362.         their output acordingly, Font_Paint, however, does not. Icons that
  363.         use outline fonts should read the graphics origin (it will still be
  364.         read correctly if output is redirected) and add it to the coordinates
  365.         passed to Font_Paint.
  366.       - Redraw should NEVER alter the icon's appearance. It is very likely
  367.         that redraw will be called several times for a single redraw
  368.         operation, if a call altered the icon's appearance then the section
  369.         plotted by the next call to redraw will not match the plotted by the
  370.         first.
  371.  
  372.                                FINISH
  373.                                ------
  374. On entry:
  375.  
  376.     R0 - The X screen coordinate of the centre of the icon.
  377.     R1 - The Y screen coordinate of the centre of the icon.
  378.     R2 - The width of the icon.
  379.     R3 - The height of the icon.
  380.     R4 - A pointer to the icon's workspace.
  381.  
  382. On exit:
  383.  
  384.      ---
  385.  
  386. Purpose:
  387.  
  388. Finish is called when the icon is removed from MegaBoard. It should free up
  389. any resources claimed by other entry points, e.g. release RMA blocks and
  390. dynamic areas, close open files etc.
  391.  
  392.                                  SAVE
  393.                                  ----
  394. On entry:
  395.  
  396.     R0 - The X screen coordinate of the centre of the icon.
  397.     R1 - The Y screen coordinate of the centre of the icon.
  398.     R2 - The width of the icon.
  399.     R3 - The height of the icon.
  400.     R4 - A pointer to the icon's workspace.
  401.     R5 - Handle of the save file
  402.  
  403. On exit:
  404.  
  405.     R0 - Number of saved parameters
  406.  
  407. Purpose:
  408.  
  409. Save is called when the user saves MegaBoard's current state to disc. If the
  410. icon has not altered it's state since initialisation this entry point should
  411. simply return with R0=0. Otherwise it should save a set of parameter strings
  412. it requires to reconstruct its current state in the save file. The format of 
  413. these strings is:
  414.  
  415. [<spaces>]<n>:[<spaces>]<string><newline>
  416.  
  417. Where n is a number between 1 and the number returned in R5 (inclusive). The
  418. precise number of parameters returned in R5 must also be saved to the file
  419. and each must be uniquely numbered, however, they need not be stored in
  420. order.
  421. These parameters should not be confused with the icon's parameters specified
  422. in the icon's definition, although the strings may be the same.
  423. The number of saved parameters is not limited.
  424.  
  425.                                  LOAD
  426.                                  ----
  427. On entry:
  428.  
  429.     R0 - The X screen coordinate of the centre of the icon.
  430.     R1 - The Y screen coordinate of the centre of the icon.
  431.     R2 - The width of the icon.
  432.     R3 - The height of the icon.
  433.     R4 - A pointer to the icon's workspace.
  434.     R5 - Number of the saved parameter (-1 if there were none)
  435.     R6 - Pointer to the string (without the header)
  436.  
  437. On exit:
  438.  
  439. Offsets from the start of the code block:
  440.  
  441. -16: A% - New X screen coordinate
  442. -12: B% - New Y screen coordinate
  443. -8:  C% - New icon width
  444. -4:  D% - New icon height
  445.  
  446.  
  447. Purpose:
  448.  
  449. Load is called once for each saved parameter when the user loads a new state
  450. from disc or once only if no parameters were saved. When a new state is
  451. loaded the special icons' initialise entry points are not called, therefore
  452. load must perform any initialisation necessary.
  453. The parameters passed to load are in the order of their numbers, as stored by
  454. save not in the order in which they were saved. Therefore the last call will
  455. contain the highest number in R5.
  456.  
  457.  
  458.                                  MESSAGE
  459.                                  -------
  460. On entry:
  461.  
  462.     R0 - The X screen coordinate of the centre of the icon.
  463.     R1 - The Y screen coordinate of the centre of the icon.
  464.     R2 - The width of the icon.
  465.     R3 - The height of the icon.
  466.     R4 - A pointer to the icon's workspace.
  467.     R5 - A pointer to the message block
  468.  
  469. On exit:
  470.  
  471. Offsets from the start of the code block:
  472.  
  473. -16: A% - New X screen coordinate
  474. -12: B% - New Y screen coordinate
  475. -8:  C% - New icon width
  476. -4:  D% - New icon height
  477.  
  478.  
  479. Purpose:
  480.  
  481. Message is called if the icon's message state is set to "on" in it's
  482. definition and MegaBoard receives a WIMP message that is passed to special
  483. icons. R5 points to a standard message block as described in the PRM.
  484.  
  485. Currently the following messages are passed:
  486.   DataLoad (Only if the file is actually dropped on the icon)
  487.   ModeChange
  488.   IconDragged
  489. Note: Strictly speaking IconDragged is not a WIMP message, but a message
  490.       passed by MegaBoard to a special icon that has been dragged by the
  491.       user.
  492.       I have applied to Acorn for a message chunk allocation, but have yet to
  493.       receive a reply, so until then the message code for IconDragged is
  494.       &F00000, which is hopefully a long way outside currently allocated
  495.       message number space.
  496.  
  497. Note: At the moment MegaBoard only passes DataLoad Messages on to special
  498.       icons, this may however change in future versions, this entry point 
  499.       should therefore first check whether the message is really a DataLoad.
  500.  
  501.  
  502.                                  MOUSE
  503.                                  -----
  504. On entry:
  505.  
  506.     R0 - The X screen coordinate of the centre of the icon.
  507.     R1 - The Y screen coordinate of the centre of the icon.
  508.     R2 - The width of the icon.
  509.     R3 - The height of the icon.
  510.     R4 - A pointer to the icon's workspace.
  511.     R5 - Button state
  512.  
  513. On exit:
  514.  
  515. Offsets from the start of the code block:
  516.  
  517. -16: A% - New X screen coordinate
  518. -12: B% - New Y screen coordinate
  519. -8:  C% - New icon width
  520. -4:  D% - New icon height
  521.  
  522. Purpose:
  523.  
  524. Mouse is called if the icon's mouse state is set to "on" in it's definition
  525. and the user clicks either Select or Adjust on the icon.
  526.  
  527. Note: the entry points described below are not supported by the current
  528. version of MegaBoard. i.e. they will not be called.
  529.  
  530.  
  531.                                    KEY
  532.                                    ---
  533. On entry:
  534.  
  535.     R0 - The X screen coordinate of the centre of the icon.
  536.     R1 - The Y screen coordinate of the centre of the icon.
  537.     R2 - The width of the icon.
  538.     R3 - The height of the icon.
  539.     R5 - Wimp Key code
  540.  
  541. On exit:
  542.  
  543. Offsets from the start of the code block:
  544.  
  545. -16: A% - New X screen coordinate
  546. -12: B% - New Y screen coordinate
  547. -8:  C% - New icon width
  548. -4:  D% - New icon height
  549.  
  550.  
  551. Purpose:
  552.  
  553. Key is called if the icon's key state is set to "on" in it's definition and
  554. the user presses a key not processed by other tasks.
  555.  
  556.                                    MENU
  557.                                    ----
  558. On entry:
  559.  
  560.     R0 - The X screen coordinate of the centre of the icon.
  561.     R1 - The Y screen coordinate of the centre of the icon.
  562.     R2 - The width of the icon.
  563.     R3 - The height of the icon.
  564.     R4 - A pointer to the icon's workspace.
  565.     R5 - X coordinate at which the menu should be opened.
  566.     R6 - Y coordinate at which the menu should be opened.
  567.  
  568. On exit:
  569.  
  570.    ---
  571.  
  572. Purpose:
  573.  
  574. This entry point is called if the icon's menu state is set to "on" in it's
  575. definition and the user moves the pointer over the "Special menu" arrow in
  576. the "Special" submenu. It should set up a menu block and open the menu with
  577. Wimp_CreateSubMenu (NOT Wimp_CreateMenu) at the coordinates specified in R5
  578. and R6.
  579.  
  580.  
  581.  
  582.  
  583.                                    MENU SELECT
  584.                                    -----------
  585. On entry:
  586.  
  587.     R0 - The X screen coordinate of the centre of the icon.
  588.     R1 - The Y screen coordinate of the centre of the icon.
  589.     R2 - The width of the icon.
  590.     R3 - The height of the icon.
  591.     R4 - Pointer to the icon's workspace.
  592.     R5 - Pointer to a block
  593.            R5+0 - Item in the icon's base menu that was selected
  594.            R5+4 - Item in the first submenu that was selected
  595.                              ...
  596.                   terminated by -1
  597.  
  598. On exit:
  599.  
  600.    ---
  601.  
  602. Purpose:
  603.  
  604. Menu select is called if the icon's menu state is set to "on" in it's
  605. definition and the user chooses an item from one of its menu.
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.                                    MENU WARNING
  613.                                    ------------
  614. On entry:
  615.  
  616.     R0 - The X screen coordinate of the centre of the icon.
  617.     R1 - The Y screen coordinate of the centre of the icon.
  618.     R2 - The width of the icon.
  619.     R3 - The height of the icon.
  620.     R4 - Pointer to the icon's workspace.
  621.     R5 - X coordinate where the submenu should be opened
  622.     R6 - Y coordinate where the submenu should be opened
  623.     R7 - Pointer to a block
  624.            R7+0 - Item in the icon's base menu that was selected
  625.            R7+4 - Item in the first submenu that was selected
  626.                              ...
  627.                   terminated by -1
  628.  
  629. On exit:
  630.  
  631.    ---
  632.  
  633. Purpose:
  634.  
  635. Menu warning is called if the icon's menu state is set to "on" in it's
  636. definition and MegaBoard receives a Menu_Warning message from the Wimp that
  637. is applicable to the icon's menu the user chooses an item from one of its
  638. menu.
  639.  
  640.  
  641.